============================================================
HyperNewt 2.0 Developer API

Last Update: September 1, 1997

Copyright (c) 1997. Foundation Systems. All Rights Reserved.
============================================================


=================
TABLE OF CONTENTS
=================

  1. Developer API
  
    A. The HyperLink Manager
    B. Creating a HyperLink Manager
    C. SaveHyperLink Function Overview
    D. ShowHyperLink Function Overview
    E. Sample HyperLink Manager Soup Entry
    F. Soup Definitions and Soup Names
    G. Sample Code And Submitting HLM's 



-------==============================================================-------
---===                       1. DEVELOPER API                         ===---
-------==============================================================-------


The following information is for developers who are interested in creating
HyperLink Managers for their own applications. Any application that supports
2.x routing of data can use HyperLinks. A developer need only to create a
HyperLink Manager (HLM) that handles the saving of and display of HyperLinked
data.



    ======================================
    ---=== A. THE HYPERLINK MANAGER ===---
    ======================================
    
There are two types of HyperLink Managers, differentiated only by the type of
data that they support:

1. Soup data: Data being HyperLinked are soup entries

2. Non-soup data: Data being HyperLinked do not belong to a soup.


Among the default HLM's installed with HyperNewt, the following applications
use (1) HLM's to store HyperLinks:

        Calls
        Cigar Box
        Dates
        Gulliver
        Home Inventory
        In/Out Box
        MORGAN
        Names
        NewtWorks
        Notes

Among the default HLM's installed with HyperNewt, the following applications
use (2) HLM's to store HyperLinks:

        Dates
        Extras Drawer
        Copperfield (Newton Books)
 

As you can see, some applications have both a Soup HLM and a Non-Soup HLM to
handle all the types of data that they deal with.



    =============================================
    ---=== B. CREATING A HYPERLINK MANAGER ===---
    =============================================

HLM's are store in the HyperLink Manager soup on a Newton device. Each HLM must
contain 3 required slots:

======================
Soup HLM required slot
======================

  a. soupname: The name of the soup where the data being HyperLinked is
     stored.

==========================
Non-Soup HLM required slot
==========================

  a. appsymbol: The symbol for the application from which the HyperLinked
     data belongs.
  
========================================================
HLM required slots -- ALL HLM'S MUST CONTAIN THESE SLOTS
========================================================

  a. SaveHyperLink: Function that creates the HyperLink information frame for
     HyperNewt.

  b. ShowHyperLink: Function that takes a HyperLink information frame and
     displays the found entry, if there is one, to the user.



The SaveHyperLink and the ShowHyperLink methods are outlined in more detail
below:



    ================================================
    ---=== C. SaveHyperLink FUNCTION OVERVIEW ===---
    ================================================

This function takes the soup entry or data that is being HyperLinked and
returns a frame containing a HyperLink Information Frame and a displayable text
title and icon to HyperNewt. The HyperLink Information Frame must contain the
following slots for each type of HyperLink Manager being created:


        // For Soup HLM's

    DefConst('kDefaultSoupHyperLinkInfoFrame,
	    {
            soupname: nil,
            timestamp: nil,
            
            shortTitle: nil, // Optional string
        }
    );
 
 
        // For Non-Soup HLM's 
 
    DefConst('kDefaultNonSoupHyperLinkInfoFrame,
        {
            appsymbol: nil,
            timestamp: nil,
            
            shortTitle: nil, // Optional string
        }
    );


The SaveHyperLink functions takes one parameter, the soup entry or data being
hyperlinked. It is the responsibility for the developer to decide, beyond the
required slots, what information she wants to add to the HyperLink Information
Frame that can locate a HyperLinked entry at a later date.

Many people will choose to store an EntryAlias, for soup entries, in the
HyperLink Information Frame. Remember that if an entry is moved to another
card, then that entry will be unresolvable from a HyperLink.



    ================================================
    ---=== D. ShowHyperLink FUNCTION OVERVIEW ===---
    ================================================

This function takes a HyperLink Information Frame to some data that has been
HyperLinked and displays the entry, if it exists, to the user. Since the
developer has written the SaveHyperLink method, she would know how to retrieve
the data and display it to the user.

If your application saves data to soups, you may want to try using HyperNewt's
default method for displaying a HyperLinked entry. Call the root method with
the following syntax:

	constant kAppSymbol := '|HyperNewt:ATOW|;

    GetRoot().(kAppSymbol).DefaultShowHyperLink with (entry, appSymbol);

where appsymbol is your application symbol and entry is your soup entry.
HyperNewt will automatically open your application and call the method
ShowFoundItem with (entry, {}) as its parameters:

    GetRoot().(appSymbol):ShowFoundItem(entry, {});

If you cannot find the entry that has been HyperLinked, return nil and
HyperNewt will alert the user that the original item could not be found.



    ====================================================
    ---=== E. SAMPLE HYPERLINK MANAGER SOUP ENTRY ===---
    ====================================================

The following code snippet details a sample HLM for the Notes application. Any
note that is HyperLinked will use the following HLM:


	/* kPaperRollSaveHyperLinkFunc
	 * ---------------------------
	 * This function extracts the title string and icon from the stationery's
	 * dataDef. It saves in the HyperLink Information frame the shortTitle
	 * (taken simply from the entry's title slot), an EntryAlias for the
	 * entry being HyperLinked, its class symbol, the soup name (required),
	 * and the entry's timestamp (required).
	 *
	 * This function returns a standard information frame back to HyperNewt
	 * to continue creating the HyperLink.
	 *
	 */

DefConst('kPaperRollSaveHyperLinkFunc, func(entry) begin
	local entryDataDef := GetEntryDataDef(entry);
	local hyperlinkinfo := Clone(kDefaultSoupHyperLinkInfoFrame);
	local title, icon;
		
	if entryDataDef then begin
		title := entryDataDef:StringExtract(entry, 1);
		icon := entryDataDef.icon;
	end;

	hyperlinkinfo.shortTitle := entry.title;
	hyperlinkinfo._alias := MakeEntryAlias(entry);
	hyperlinkinfo.class := ClassOf(entry);
	hyperlinkinfo.soupName := ROM_paperRollSoupName;
	hyperlinkinfo.timestamp := entry.timestamp;
		
	return { title: title, icon: icon, hyperlinkinfo: hyperlinkinfo };
end);


	/* kPaperRollShowHyperLinkFunc
	 * ---------------------------
	 * This function tries to first resolve the entry alias
	 * for the note stored in the hyperlink. If present, the function
	 * calls a default method of HyperNewt to display the entry,
	 * otherwise nil is returned (and HyperNewt will alert the
	 * user that the original item could not be found).
	 *
	 */

DefConst('kPaperRollShowHyperLinkFunc, func(hyperlinkInfo) begin
	local entry := EntryFromObj(hyperlinkinfo);
	local app := GetRoot().('|HyperNewt:ATOW|);
	
	if entry and app then begin
		if app:PrefsLookup('displayWithNotepad) then
			return call app.DefaultShowHyperLink with (entry, 'paperroll);
		else return call app.DefaultShowHyperLink with (entry, kAppSymbol);
	end;

	return nil;
end);


The complete HyperLink Manager soup entry frame for the Notepad HLM is shown
below. Add this entry to the HLM soup to support the use of HyperLinks in the
Notepad application:

  {
    soupname: ROM_paperRollSoupName,
    SaveHyperLink: kPaperRollSaveHyperLinkFunc,
    ShowHyperLink: kPaperRollShowHyperLinkFunc,
  }



    ====================================================
    ---=== F. SOUP DEFINITIONS AND SOUPNAMES ===---
    ====================================================

The following are the soup definition and soup name for the HyperLink Manager
Soup. When creating a HyperLink Manager, be sure to check for the presence of
the HyperLink Manager soup before hand. To ensure proper operation, *DO NOT*
create the HyperLink Manager Soup if it is not present. 

HyperNewt installs the default HLM Soup only if it is not currently installed.
If you create and add one entry to the HLM soup, new users will not be able to
use HyperLinks in any application other than your own.


DefConst('kHyperLinkManagerSoupName, "HyperLink Manager");
DefConst('kHyperLinkManagerSoupDef,
	{	
		name: kHyperLinkManagerSoupName,
		userName: kHyperLinkManagerSoupName,
		ownerApp: kAppSymbol,
		ownerAppName: kAppName,
		userDescr: "This soup is used by" && kAppName,
									
		indexes: [
					{ structure: 'slot, path: 'appsymbol, type: 'symbol }, 
					{ structure: 'slot, path: 'soupname, type: 'string },
				 ],
	}
);



    =================================================
    ---=== G. SAMPLE CODE AND SUBMITTING HLM'S ===---
    =================================================

The code for all the default HLMs that ship with HyperNewt is available from
the HyperNewt web page at:

    http://www.tow.com/newton/hypernewt/
    
If you come up with a better HLM for any of the default HLM's, email your
solution to Foundation Systems and we will consider it for inclusion in the
next release of HyperNewt. If you have an application that supports HyperLinks
and would like your application's HLM to be included among the default HLM's
that ship with HyperNewt, again, email us and your HLM will be considered for
inclusion.